This document provides a brief overview of the WebSTAR Server Suite V release. Also included are basic installation and configuration instructions. For the latest information, please check <http://www.webstar.com/>.
4D WebSTAR V is a set of powerful and easy to use servers for OS X. Currently the suite includes Web, FTP, and WebDAV services, and the 4D Mail server.
The suite also contains an Admin Server application for handling communication between the Admin Client and the server applications:
Admin Client <-> Admin Server <-> 4D Mail and Web Servers <-> Plug-Ins
In addition, the Admin Server is also responsible for monitoring any other servers in the Suite (e.g. the Web Server) and relaunching them should they unexpectedly quit.
Delegating Authority
The Admin Server supports multiple usernames and passwords, and two administration levels. Several Web Server settings (including those for Security, Logging, and CGIs) are configurable on a per-Web host basis, and administration of these host-specific settings can be delegated. In a similar way, 4D Mail server users are organized into "post offices," which can be managed by separate sub-administrators.
A Web host and a Mail post office with the same name automatically form a "Settings Group" for unified, single-window administration in the Admin Client.
The Launcher and Monitor Applications
These applications are used for launching and viewing the status of the 4D WebSTAR Server Suite. The Monitor application is similar to the Admin Client, and communicates with the Server Suite via the Admin Server application.
To install 4D WebSTAR Server Suite V, follow these steps:
IMPORTANT: If you are upgrading from a previous version, please skip to the appropriate "Upgrading..." section.
WARNING: Other server processes running on the machine may cause port conflicts. Before installing, make sure Web Sharing and FTP Access are turned off in the System Preferences Sharing panel.
1. Open the Users panel in Mac OS X System Preferences.
2. Create a new "user" called "webstar", with a short name of "webstar". This is required to ensure security and to minimize file permission/privilege issues.
WARNING: Do not give this user administration privileges. Doing so is a security risk.
IMPORTANT: When working with files in the Finder that WebSTAR will need access to, you should always be logged in as the "webstar" user.
3. Close System Preferences.
4. Launch the 4D WebSTAR V Installer. When prompted, enter the user name and password of a default Mac OS X Admin-level user.
NOTE: If you are not sure which user name and password to use, check the System Preferences Users panel for a user of kind "Admin."
5. Run the Easy Install option. 4D WebSTAR V will be installed into the Applications folder of the Startup Disk.
6. Launch 4D WebSTAR V using the Launcher application in the 4DWebSTAR folder.
NOTE: The Launcher application also starts the 4D WebSTAR Monitor application. However, you cannot log in with the Monitor until you have created an Admin user with the Admin Client.
7. Use the ProcessViewer application (in Applications/Utilities) to make sure that the Admin Server (two "WSAdminServer" processes) and the Web Server ("WSWebServer", and if the CGI plug-in is installed, "WSCGIServer") are both running. You may wish to temporarily reduce the default "Sample every" rate to 3 or 4 seconds to ensure that you are viewing the most recent information.
8. Test your Web site with a browser on the same machine (e.g. http://localhost/)
9. Launch the WebSTAR Admin Client application in the 4DWebSTAR/AdminClient folder.
10. From the Connection dialog, log in to '127.0.0.1' on port '9494', with your prefered user name and password (both are case sensitive).
NOTE: When logging into the Admin Server for the first time from the same machine ('127.0.0.1'), the user name and password that you enter in the Connection dialog box will be used as the master user name and password. The password should be unique and secure (e.g. FxGe343Sds).
NOTE: Setting up the encrypted connection to the Admin Server may take a while.
11. Select "DefaultSite" when asked to select a Settings group.
NOTE: If "DefaultSite" does not appear as an option, choose "Admin" instead. After connecting, select the Web Hosts panel from the Web Server group and click on Save. Then select Disconnect from the Admin Client's File menu to close the connection. Reconnect, and the "DefaultSite" option should appear.
12. Select the License panel in the Admin Server panel group, and enter your serial number. Please check your registration card for further details.
NOTE: 4D WebSTAR will run in a 2-hour demo mode without a license.
13. Review the Web Server's settings, and make changes if necessary.
14. Select Disconnect from the Admin Client's File menu to close the connection.
15. Quit the 4D WebSTAR Server Suite Launcher application (quitting and relaunching is required to cancel out of the 2-hour demo mode).
16. Select Log Out from the Apple menu, and log back into Mac OS X as the new "webstar" user.
17. Copy your Web documents (HTML files, images, etc.) into the 4DWebSTAR/WebServer/DefaultSite folder.
IMPORTANT: When working with files in the Finder that WebSTAR will need access to, you should always be logged in as the "webstar" user.
18. Any error files (e.g. error.html, noaccess.html) should be placed in the DefaultSite/errors folder, and renamed using the error number (e.g. 404.html for 'file not found', 403.html for 'access forbidden', 401.html for 'authenticated required', etc.).
19. If you wish to run 4D WebSTAR V from Mac OS X Log In, add the Launcher application to Login Items in the System Preferences Login panel, and make sure that "Automatically log in" is enabled.
20. If, on the other hand, you wish to run 4D WebSTAR V prior to Login as a background process, run the "Create Startup Item" custom install option in the installer.
IMPORTANT: If you run 4D WebSTAR V from Startup, it will run in the background with no interface. However, you can use the WebSTAR Monitor Application to view the server's activity.
WARNING: You should never configure WebSTAR to run from both Log In and Startup.
IMPORTANT: When working with files in the Finder to which WebSTAR will need access, you should always be logged in to Mac OS X as the "webstar" user.
1. Create unique folders for each distinct Web site in the 4DWebSTAR/WebServer folder (you can use other locations, but this is recommended).
2. Copy your Web documents (HTML files, images, etc.) for each site into the appropriate folder.
3. Any error files (e.g. error.html, noaccess.html) for each site should be placed in an errors subfolder (within each Web host folder) and renamed using the error number (e.g. 404.html for 'file not found', 403.html for 'access forbidden', 401.html for 'authenticated required', etc.).
4. Launch WebSTAR V using the Launcher application in the 4DWebSTAR/AdminServer folder.
5. Log in to the Admin Server using the 4D WebSTAR Admin Client.
6. Select "Admin" when asked to select a Settings group.
7. Create new Virtual Host references in the Web Server Web Hosts panel. Make sure that both the Sites and Routing tables contain valid data--Routing entries with invalid hostname or site reference will not be saved.
WARNING: Make sure your configured ports match those in the Web Connections panel.
NOTE: You can map more than one hostname variant (e.g. mydomain.com, www.mydomain.com) to a single Web host site, allowing you to have only one settings file for all the variants.
IMPORTANT: The Virtual Host routing table is order-dependent, and may need to be reordered.
8. Disconnect and reconnect the Admin Client, and on log-in, select the Web host that you wish to administer.
9. Make any Web host specific changes that you need in the Web Host and Web Security panel groups.
10. Test the sites with a browser.
NOTE: You can copy the settings of one Web host to another by duplicating and renaming Web host preferences files located in the 4DWebSTAR/WebServer folder. Make sure that no WebSTAR V applications or processes are running when you do this. Any new preference file name must be valid Web host site name followed by '.prefs.xml' (e.g. MySite.prefs.xml).
To upgrade from a previous version of 4D WebSTAR 5.x:
1. Quit all running 4D WebSTAR Applications. If you are running the server in the background from Startup Items, use the Admin Client's Shutdown command (in the Admin Server menu), then quit the Client.
2. Backup all 4D WebSTAR 5.x folders and files. You may get an permissions error about not being able to copy certain files, but it is OK to click Continue. In almost all cases, the problematic files are executables that you do not need to back up.
3. If you have any files (e.g. CGIs) in the 4DWebSTAR file tree with custom ownership settings (i.e files are not owned by "webstar"), temporarily lock them via the Finder.
4. Launch the 4D WebSTAR V Installer. When prompted, enter the user name and password of a default Mac OS X Admin-level user.
NOTE: If you are not sure which user name and password to use, check the System Preferences Users panel for a user of kind "Admin."
5. Run the Easy Install option. The Installer will upgrade the existing 4DWebSTAR folder in Applications. None of your settings or Web content should be overwritten.
6. Quit the Installer.
7. Use the Finder to unlock any files locked in step 2.
8. Launch WebSTAR as you normally would (from the Launcher or by restarting).
9. Log in with the Admin Client and select the "Installed Components" panel. Confirm that all components have been upgraded.
10. Test all services (e.g the Web Server) with appropriate clients (e.g. a Web browser) to confirm that they are working properly.
IMPORTANT: WebSTAR 4.x will not run under Mac OS X, and WebSTAR V will not run under earlier versions of the Mac OS.
WARNING: Other server processes running on the machine may cause port conflicts. Before installing, make sure Web Sharing and FTP Access are turned off in the System Preferences Sharing panel.
IMPORTANT: If you wish to migrate from WebSTAR Mail 4 to 4D Mail on the same machine, you must be careful to begin the migration process before shutting down your old mail sever. Please run the "4D Mail Migration Tool" custom install option on an OS X machine, then carefully read "4D Mail Migration.txt" (in the Applications/4DWebSTAR/MailboxServer folder).
To upgrade from 4D WebSTAR 4.x:
1. Quit all running 4D WebSTAR 4.x applications.
2. Backup all 4D WebSTAR 4.x folders and files.
3. Boot into Mac OS X on the machine that you will use for 4D WebSTAR V.
4. Open the Users panel in Mac OS X System Preferences.
5. Create a new "user" called "webstar", with a short name of "webstar". This is required to ensure security and to minimize file permission/privilege issues.
IMPORTANT: Do not give this user administration privileges. Doing so is a security risk.
IMPORTANT: When working with files in the Finder to which WebSTAR will need access, you should always be logged in as the "webstar" user.
6. Close System Preferences.
7. Launch the 4D WebSTAR V Installer. When prompted, enter the user name and password of a default Mac OS X Admin-level user.
NOTE: If you are not sure which user name and password to use, check the System Preferences Users panel for a user of kind "Admin."
8. Run the Easy Install option. 4D WebSTAR V will be installed into the Applications folder of the Startup Disk.
IMPORTANT: If you need to migrate Web and FTP server settings, DO NOT launch 4D WebSTAR yet.
9. Log out of Mac OS X and log back in as the special "webstar" user.
10. Copy your default Web site content from the main WebSTAR 4.x folder into the 4DWebSTAR/WebServer/DefaultSite folder.
11. Leave your virtual host folders in their original locations, or move them into the 4DWebSTAR/WebServer folder, at the same level at the DefaultSite folder (recommended).
12. Copy your 4.x WebSTAR Virtual Hosts Settings file into the 4DWebSTAR/WebServer/plug-ins folder. If you do this, on first launch the Virtual Hosts plug-in will attempt to create appropriate entries in its tables.
13. Any error files (e.g. error.html, noaccess.html) for each site should be placed in an errors subfolder (within each Web host folder) and renamed using the error number (e.g. 404.html for 'file not found', 403.html for 'access forbidden', 401.html for 'authenticated required', etc.).
IMPORTANT: When working with files in the Finder that WebSTAR will need access to, you should always be logged in as the "webstar" user.
14. Copy your 4.x WebSTAR Settings file into the 4DWebSTAR/WebServer folder. This will be used to migrate some settings to WebSTAR V's preferences.
15. If you have one, copy the WebSTAR FTP Data folder from the 4.x Plug-Ins folder to the new 4DWebSTAR/WebServer folder.
16. Launch the 4D WebSTAR V Installer again, but only run the "Configure File Permissions" custom install option.
17. Launch 4D WebSTAR V using the Launcher application in the 4DWebSTAR folder.
NOTE: The Launcher application also starts the 4D WebSTAR Monitor application. However, you cannot log in with the Monitor until you have created an Admin user with the Admin Client.
18. Use the ProcessViewer application (in Applications/Utilities) to make sure that the Admin Server (two "WSAdminServer" processes) and the Web Server ("WSWebServer", and if the CGI plug-in is installed, "WSCGIServer") are both running. You may wish to temporarily reduce the default "Sample every" rate to 3 or 4 seconds to ensure that you are viewing the most recent information.
19. Launch the 4D WebSTAR Admin Client application in the 4DWebSTAR/AdminClient folder.
20. From the connection dialog, log in to '127.0.0.1' on port '9494', with your prefered user name and password (both are case sensitive).
NOTE: When logging into the Admin Server for the first time from the same machine ('127.0.0.1'), the user name and password that you enter in the Connection dialog box will be used as the master user name and password. The password should be unique and secure (e.g. FxGe343Sds).
NOTE: Setting up the encrypted connection to the Admin Server may take a while.
21. Select "Admin" when asked to select a Settings Group.
22. Select the License panel in the Admin Server panel group, and enter your serial number. Please check your registration card for further details.
NOTE: 4D WebSTAR will run in a 2-hour demo mode without a license.
23. Review the Web Server's settings, and make changes if necessary.
24. Review any migrated Virtual Host and FTP settings.
25. If you wish to run the Mail server, select the Settings panel in the Admin Server Group. Turn on the checkboxes for the SMTP and Mailbox Servers and click Save only once. Watch the Launcher window or the ProcessViewer utility to see when the two server processes start (it may take a minute or two).
26. Select Disconnect from the Admin Client's File menu to close the connection.
27. Quit and relaunch the 4D WebSTAR Server Suite using the Launcher application (quitting and relaunching is required to cancel out of the 2-hour demo mode).
28. Connect with the Admin Client to confirm that everything is still operational. If you activated the SMTP Server and Mailbox Server processes earlier, make sure that their panel groups now show up.
IMPORTANT: If the Launcher has problems starting server processes or if you cannot connect with the Admin Client, you may need to restart your machine to allow a clean launch.
29. Select Disconnect from the Admin Client's File menu to close the connection.
30. If you wish to run 4D WebSTAR V from Mac OS X Log In, add the Launcher application to Login Items in the System Preferences Login panel, and make sure that "Automatically log in" is enabled.
31. If, on the other hand, you wish to run 4D WebSTAR V prior to Login as a background process, run the "Create Startup Item" custom install option in the installer.
IMPORTANT: If you run 4D WebSTAR V from Startup, it will run in the background with no interface. However, you can use the WebSTAR Monitor Application to view the server's activity.
WARNING: You should never configure WebSTAR to run from both Log In and Startup.
Currently the 4D Mail Migration Tool is designed for migrating accounts running on 4D WebSTAR 4 servers, but can be adapted for use with other mail servers.
It is only available as an OS X application, but requires that your old mail server is running, so you will need two machines to complete the migration process. We recommend that you run the utility from an OS X machine that will become your new server, and leave the old mail server running in its original location.
However, if you wish to migrate from WebSTAR Mail 4 to 4D Mail on the same machine, you must be careful to begin the migration process before shutting down your old mail sever.
For more information on migrating to 4D Mail, please run the "4D Mail Migration Tool" custom install option on an OS X machine, then carefully read "4D Mail Migration.txt" (in the Applications/4DWebSTAR/MailboxServer folder).
- If you create an Admin Server log-in username that contains spaces, the user will not be able to log in.
- Initializing Admin Client/Server encrypted connections may take a while.
- Launching the WebSTAR Server Suite too soon after quitting may cause problems since the Admin ports (9494 and 9495 by default) may not yet be closed out by the operating system. Be sure to quit all applications (Launcher, Monitor and Client) before attempting to relaunch.
- If you are unable to connect with the Admin Client for no apparent reason, check the Launcher application's logging area (the Launcher's green zoom button shows and hides this output). If it shows SSL "certificate unknown" errors on attempted Admin Client connections, check the date on your machine--it may not be correct.
- Drag and drop between tables sometimes cause unusual but transient cosmetic behaviors.
Web Server
- HTTP redirects (302s) are currently processed like errors. This means that the contents of a generic error file is served along with a redirect, and sometimes the redirect fails if a CGI or plug-in other than Default handles the error page. To avoid this problem, add a simple text file named "302" to your errors folder, with an extension that is not handled by a plug-in or CGI (e.g. "302.txt").
4D Mail
- If you cannot select folders via the Choose buttons on the 4D Mail administration panels, temporarily activate the Web Server in the Admin Server Settings panel. Once you have successfully created the folders, you can deactivate the Web Server again.
Flexmail Plug-in
- Flexmail does not yet support saving XML-reserved characters (including &, ", and < ) in settings. If you encounter problems after using these characters in settings fields, quit all WebSTAR applications and use a text editor to remove the offending character(s) from the WSWebServer.prefs.xml. Then relaunch 4D WebSTAR.
- Flexmail SAVECUSTOM only works if the virtual host root is at the same level of DefaultSite (in the WebServer folder). To work around this, try creating a symbolic link (the Unix equivalent of an alias) that points to the real location, so that WebSTAR thinks the virtual host is in the WebServer folder.
FTP Plug-in
- As a Carbon plug-in, WebSTAR FTP does not support file names over 31 characters, even though it is now running on OS X.
- The Transmit FTP client is incompatible with WebSTAR FTP accounts that have blank passwords. If you see this problem, please give the account a password or use a different FTP client.
- FTP clients (including Netscape Navigator) may have compatibility issues with WebSTAR FTP. Changing the reported server name to "Unix WebSTAR FTP" in the FTP Connections panel of the Admin Client usually solves the problem.
- You may experience problems with the storage limit setting in FTP. Quitting and relaunching 4D WebSTAR should resolve this issue.
Log Plug-in
- Archiving schedules may not appear to activate as configured. This is because the replacement file will not be created until the log buffer is full.
- In some cases where the Web log is archived by schedule, some data that belongs in the previous log file is inserted at the beginning of the new file. Lower your log buffer size to reduce or eliminate this problem.
Mac OS X File Permissions
- 4D WebSTAR may not have read and/or write access to files created in the Finder. To solve this issue, we recommend that you create or copy all new folders and files while logged in to the Finder as the special "webstar" user, or via a WebSTAR file sharing service (WebDAV or FTP).
- The 'Configure File Permissions' custom install option in the 4D WebSTAR Installer ensures that WebSTAR will have read and write permissions for all files within the /Applications/4DWebSTAR hierarchy, including new folders and files created since the initial install.
Search Plug-in
- A search index file is not available for queries unless it appears in the Search index table. This is standard behavior.
Security Plug-in
- Renaming reusable security tables (including User lists, Permissions tables, and Allow/Deny tables) will result in the loss of previous content. Please export table contents before renaming.
- There is currently a limit of 50 authenticators per Web server (including all Web Hosts).
SSI Plug-in
- Currently, the SSI Plug-in does not include support for Mac OS aliases. Please
- SSI does not yet support calls to the WebSTAR API parameters (e.g. pi_).
- SSI does not yet provide tag services for other plug-ins.
Virtual Hosts
- Renaming a Virtual Host (via the Admin Client) will not automatically rename its preference file in the 4DWebSTAR/WebServer folder. You will need to quit the server and do this manually.
WebDAV Plug-in
- Currently, the WebDAV Plug-in does not include support for Mac OS aliases. Aliases on WebSTAR WebDAV volumes will appear as zero K files.
- Files that are processed by other plug-ins and CGIs will be processed when WebDAV requests them. There is currently no workaround for plug-in processing. In the case of CGIs, create a new Web host using a different port or hostname that points to the same root as your normal host. Then disable all CGI settings for the new host.
- Windows XP's built-in WebDAV client may have problems logging in because it passes an incorrect username to WebSTAR. Instead of just 'username' it uses 'hostname\username'. Until Microsoft fixes this problem, you will need to add an extra login to your user lists for Windows XP users (e.g. 'jsmith' and 'www.mydomain.com\jsmith').
System
- Make sure that your Energy Saver sleep settings are set to never. If the machine goes to sleep and then is reactivated, you may need to quit and relaunch 4D WebSTAR since networking must be reinitialized.
Misc.
- If you continue to have problems successfully running the 4D WebSTAR V, check the Launcher application's logging area (the Launcher's green zoom button shows and hides this output) to view the WebSTAR Server Suite initialization process.
If you are running 4D WebSTAR V in the background, you should use the Console application in Applications/Utilities instead. Keep in mind that the Console log keeps old information, so watch the time stamps. You may also want to set the Console log preferences to about 200 lines to reduce the time it takes to load.
Though 4D is not responsible for maintaining or helping you use the software, 4D does at its discretion offer free technical support for the first ninety (90) days after you register your new WebSTAR product. Technical support can be obtained in the following ways:
For the US and Canada only (except Quebec):
• Our Web site: <http://www.webstar.com/>
• Telephone: (408) 557-4600
Some charges may apply for additional telephone support.
• US Mail: 4D, Inc. ATTN: WebSTAR Support
3031 Tisch Way, Suite 900, San Jose, CA 95128, USA
• Our mail discussion lists:
Sign up at <http://www.webstar.com/support/mailinglist.html>
For other countries:
• Contact your local 4D distributor at <http://www.4d.com/world/>.
• Our Web site: <http://www.webstar.com/>
• Our mail discussion lists:
Sign up at <http://www.webstar.com/support/mailinglist.html>
